home *** CD-ROM | disk | FTP | other *** search
/ Aminet 32 / Aminet 32 (1999)(Schatztruhe)[!][Aug 1999].iso / Aminet / dev / debug / TRSaferPtch.readme < prev    next >
Text File  |  1999-07-01  |  13KB  |  372 lines
  1. Short:    Safer Setfunctions Debug Tools
  2. Author:   thor@math.tu-berlin.de (Thomas Richter)
  3. Uploader: thor@math.tu-berlin.de (Thomas Richter)
  4. Version:  2.08
  5. Type:     dev/debug
  6. Requires: An Amiga, every model, every OS will do
  7.  
  8. _____________________________________________________________________________
  9.  
  10.                         The THOR-Software Licence
  11.  
  12.  
  13. This License applies to the computer programs known as "SaferPatches" and 
  14. "ShowPatch". The "Program", below, refers to such program.
  15.  
  16.  
  17. The programs and files in this distribution are freely distributable
  18. under the restrictions stated below, but are also Copyright (c)
  19. Thomas Richter.
  20.  
  21.  
  22. Distribution of the Program by a commercial organization without written
  23. permission from the author to any third party is prohibited if any payment
  24. is made in connection with such distribution, whether directly
  25. (as in payment for a copy of the Program) or indirectly (as in payment
  26. for some service related to the Program, or payment for some product
  27. or service that includes a copy of the Program "without charge";
  28. these are only examples, and not an exhaustive enumeration of prohibited
  29. activities). However, the following methods of distribution involving
  30. payment shall not in and of themselves be a violation of this restriction:
  31.  
  32.  
  33. (i) Posting the Program on a public access information storage and
  34. retrieval service for which a fee is received for retrieving information
  35. (such as an on-line service), provided that the fee is not
  36. content-dependent (i.e., the fee would be the same for retrieving the same
  37. volume of information consisting of random data).
  38.  
  39.  
  40.  
  41. (ii) Distributing the Program on a CD-ROM, provided that the files
  42. containing the Program are reproduced entirely and verbatim on such
  43. CD-ROM, and provided further that all information on such CD-ROM be
  44. redistributable for non-commercial purposes without charge.
  45.  
  46.  
  47.  
  48. Everything in this distribution must be kept together, in original
  49. and unmodified form.
  50.  
  51.  
  52.  
  53.  
  54. Limitations.
  55.  
  56. THE PROGRAM IS PROVIDED TO YOU "AS IS," WITHOUT WARRANTY. THERE IS NO
  57. WARRANTY FOR THE PROGRAM, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
  58. LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  59. PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE ENTIRE
  60. RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD
  61. THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
  62. SERVICING, REPAIR OR CORRECTION.
  63.  
  64.  
  65.  
  66. IF YOU DO NOT ACCEPT THIS LICENCE, YOU MUST DELETE ALL FILES CONTAINED IN
  67. THIS ARCHIVE.
  68.  
  69. _____________________________________________________________________________
  70.  
  71.  
  72. Purpose of this program:
  73.  
  74.     Make the SetFunction (= patch function) of the OS safer, allow 
  75.     installation and removal of patches in any order.
  76.     Record the patches made and the program that made the patch.
  77.  
  78. This program is mainly intended as a debugging tool, for recording the patches
  79. installed and to capture illegal patches. It is, however, adviced to run with
  80. SaferPatches installed permanently.
  81.  
  82. SaferPatches will free the additional memory occupied by the patched functions
  83. automatically if a library is flushed later on.
  84.  
  85.  
  86.     SYNOPSIS:
  87.  
  88. SaferPatches    INSTALL    REMOVE REMEMBER WARN
  89.  
  90.  
  91. INSTALL        Add the "SaferPatches" patch to the system.
  92. REMOVE        Remove "SaferPatches" from the system. You are, however,
  93.         "recommanded" not to remove it once you've started it.
  94.         
  95. REMEMBER    This option can be given together with INSTALL. If present,
  96.         SaferPatches will store the names of the programs together
  97.         with the patch they added.
  98.  
  99. WARN        Saferpatches will guru with 0x10000026 if a removed vector
  100.         is still used.
  101.  
  102.  
  103.     SYNOPSIS:
  104.  
  105. ShowPatch    fd_dir
  106.  
  107.     Shows all patches added to the system, together with the entry point
  108.     and the program that added the patch, if available - see the
  109.     REMEMBER option of the Saferpatches program.
  110.  
  111.     If the "fd_dir" is given, ShowPatch will read standard ".fd"
  112.     library descriptions from that subdirectory and will present the
  113.     name of the entry point that has been patched as well.
  114.  
  115.  
  116. _____________________________________________________________________________
  117.  
  118. Compatibility:
  119.  
  120.     "SaferPatches" is NOT compatible to the following illegal patches:
  121. (see below for what is considered to be legal)
  122.  
  123.     -CEDPatch
  124.  
  125.  
  126.  
  127. The way "SaferPatches" operates conflicts with my debug utility "MemSniff".
  128. If you want to run both, "MemSniff" and "SaferPatches", you should add the
  129. command line option "SNIFF" to SaferPatches. You shouldn't provide that
  130. option in other situations.
  131.  
  132.  
  133. VirusZ might report that libraries got patched from time to time. This is
  134. because SaferPatches modifies the Expunge vector of all libraries in order
  135. to free the memory occupied by the patches if the library gets closed. This
  136. warning message is harmless.
  137.  
  138.  
  139. IMPORTANT:    !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  140. Saferpatches MUST be run BEHIND SetPatch !!!!!!!!!!!!!!!!!
  141. IMPORTANT:    !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!    
  142.  
  143.  
  144. SaferPatches IS compatible to the debug tool PatchWork.
  145.  
  146. _____________________________________________________________________________
  147.  
  148. Gurus:
  149.  
  150.     Because "SaferPatches" is supposed to be a debug utility, it may
  151. create "guru meditations", i.e. software alerts. The following alerts may
  152. be created by SaferPatches:
  153.  
  154. 0x01000020        Patch vector out of range.
  155.         A program tried to patch a vector in a library that isn't
  156.         present.
  157.  
  158. 0x01000021        Entry is not patchable.
  159.         A program tried to install a patch into a vector that can't
  160.         be patched. Some vectors, like the GetCC() vector of
  161.         the exec lib are directly inlined functions that can't be
  162.         changed with SaferPatches. Same goes for the DOS library
  163.         of releases 32 to 35, but this has changed starting with
  164.         releases 36 and up of the OS.
  165.  
  166. 0x01000022        No mem for patch vector.
  167.         SaferPatches failed to allocate memory for the patch.
  168.  
  169. 0x01000023        Patched vector to ROM.
  170.         A program attempted to patch one ROM vector to a second
  171.         vector which is actually in the ROM. Replacing one system
  172.         function by a different one is considered to be illegal.
  173.  
  174. 0x01000024        Found libentry without patches
  175.         SaferPatches found a library in its patch list that isn't
  176.         actually patched. This is an internal failure and shouldn't
  177.         occur.
  178.  
  179. 0x01000025        Unsafe patch
  180.         A program tried to patch one vector that can't be patched in
  181.         a safe way because it is called by the SetFunction procedure
  182.         itself. One example is "SetFunction", or "SumLibrary".
  183.  
  184. 0x01000026        Removed libentry called
  185.         A libvector that has been removed was illegally called again.
  186.         A program restored an older patch, but was still calling the
  187.         obsolete return vector. This can only happen with WARN 
  188.         enabled.
  189.  
  190. 0x01000027        Function pointer is NULL
  191.         Somebody tried to patch a function to NULL.
  192.  
  193. _____________________________________________________________________________
  194.  
  195. Legal vs. illegal patching:
  196.  
  197. Three operations are considered to be "legal" patching operations:
  198.  
  199. 1)    Install a patch
  200. 2)    Remove a patch
  201. 3)    Verify, if a given patch is installed.
  202.  
  203. 3) is new to this implementation of SaferPatches and not having it messed the
  204. system with the RTPatch program.
  205.  
  206.  
  207. A legal way how to install a patch: (with or without SaferPatches)
  208.  
  209.     -Call Forbid() or even Disable() in critical cases.
  210.     -Load the address of the new function in d0, the offset in a0,
  211.      the library and a1, and ExecBase in a6.
  212.     -Call SetFunction()
  213.     -Store the return value of SetFunction as pointer to the old function.
  214.     -Call Permit() or Enable().
  215.  
  216.  
  217. The following methods of installing patches ARE ILLEGAL:
  218.  
  219.     -Forgetting to Permit()/Forbid().
  220.     -Reading the vector directly from the library vectors instead of
  221.      using the return value.
  222.     -Using the return code of SetFunction for anything else except
  223.      jumping into the old code.
  224.     -Patching one OS function to a different one.
  225.     -Patching functions that can't be patched, like inline functions
  226.      or functions called by SaferPatches. This includes the functions
  227.      CacheClearU(), SetFunction() and SumLibrary().
  228.     -Using anything else but the return code of SetFunction for calling
  229.      the old function.
  230.     -Writing the new function directly into the vector offset.
  231.  
  232.  
  233. A legal way to remove a patch: (with SaferPatches)
  234.  
  235. Even though the procedures presented below remove a patch vector safely from 
  236. the os (ONLY the vector, NOT the code) IT DOES NOT PREVENT, WITH SAFERPATCHES 
  237. INSTALLED OR NOT, THAT SOME TASK IS STILL EXECUTING THE CODE OF YOUR PATCH. 
  238. This is, you may not freely deallocate the memory your patch resides in.
  239. Removing patches is always a problem, it is not recommended to release the
  240. patch memory at all UNLESS YOU CAN REALLY, ABSOLUTELY ENSURE THAT NO TASK IS 
  241. EXECUTING YOUR CODE. There is, however, no general guide line how to do that.
  242.  
  243. The following algorithm "works" IF YOU KNOW the patch is installed and
  244. SaferPatches is installed. It DOES NOT work around general patch caveats:
  245.  
  246.     -Load d0 with the return code of SetFunction you got when installing 
  247.      the patch. Load a1 with the base address of the library. Load a6
  248.      with execbase.
  249.     -Call SetFunction().
  250.  
  251.  
  252. A legal and safe way to remove a patch: (with or without SaferPatches)
  253.  
  254. The following mechanism is recommended for general patch removal. Please
  255. note THAT THIS MIGHT FAIL and you won't be able to remove your patch at all.
  256. It WON'T fail with SaferPatches, though. It does, too, not work around the
  257. code memory caveats from above.
  258.  
  259.     -Call Forbid() or Disable().
  260.     -Call SetFunction() with the same arguments AS IF you are installing
  261.      the patch again, this is:
  262.      Load the address of the new function in d0,the library base in a1
  263.      and ExecBase in a6 and offset in a0. Call SetFunction.
  264.     -Check the return code:
  265.         If this is the entry point of your patch, then:
  266.         -Load d0 with the return code of SetFunction when installing 
  267.          the patch. Load a1 with the base address of the library. 
  268.          Load a6 with execbase.
  269.         -Call SetFunction().
  270.         These calls will remove your patch.
  271.         
  272.         If this is not the address of your patch, then:
  273.         -Load d0 with THIS return code of SetFunction, i.e. what
  274.          you got from the call a few lines on top. Load a1 with 
  275.          the base address of the library. Load a6 with execbase.
  276.         -Call SetFunction().
  277.         This will re-install the last patch. 
  278.         YOUR PATCH CAN'T BE REMOVED SAFELY IN THIS CASE 
  279.         (SaferPatches is not running).
  280.     -Call Permit() or Enable().
  281.  
  282.  
  283. The following methods of removing a patch ARE ILLEGAL:
  284.  
  285.     -Use anything else but the return code of the installing SetFunction
  286.      for removing the patch again.
  287.     -Removing the new function by writing the old return code directly
  288.      into the vector offset.
  289.     -Executing the steps above not completely in Forbid() mode, i.e.
  290.      call Permit() in between or calling any other os function that
  291.      might break the forbid.
  292.  
  293.  
  294. A legal way how to verify whether your patch is still installed: 
  295.  
  296. This algorithm can be used to check if your patch is still active, using
  297. SaferPatches. It will only tell you if the patch is "frontmost" if Safer-
  298. Patches is not installed.
  299.  
  300.     -Call Forbid() or Disable()
  301.     -Call SetFunction with the same arguments AS IF you are installing
  302.      the patch again, this is:
  303.      Load the address of the new function in d0,the library base in a1
  304.      and ExecBase in a6 and offset in a0. Call SetFunction.
  305.     -Check the return code. If it is the same pointer you passed in d0
  306.      to SetFunction, your patch is still active. It has been installed
  307.      now, by the procedure above and must/can be removed if desired/
  308.      required with a second call to SaferPatches. It will NOT be
  309.      installed twice by this algorithm, neither with nor without 
  310.      SaferPatches.
  311.     -Call Permit() or Enable().
  312.  
  313. This method is used by the RTPatch program and also considered to be legal.
  314.  
  315. The following verify methods are considered to be illegal:
  316.  
  317.     -Failing to call Forbid().
  318.     -Reading the vector entry from the vector base directly.
  319.  
  320.  
  321. How to check if SaferPatches is installed:
  322.  
  323.     -Call FindPort("SetMan"). If the result is non-zero, SaferPatches,
  324.      SetMan or PatchControl is installed. Do not use this port for
  325.      anything else.
  326.  
  327.     -Call FindPort("SaferPatches.rendezvous"). If the result is non-
  328.      zero, it's specifically SaferPatches. There's usually no need to
  329.      to check for this port. Don't use this port for anything else!
  330.  
  331. _____________________________________________________________________________
  332.  
  333. New in 2.08:
  334.  
  335. Hopefully fixed a minor compatibility problem with PoolMem and MuGuardian-
  336. Angel.
  337. _____________________________________________________________________________
  338.  
  339.  
  340. New in 2.07.1:
  341.  
  342. Updated the ReadMe a bit.
  343.  
  344.  
  345. New in 2.07:
  346.  
  347. Added another GURU, added the WARN option to turn off the 0x01000026 guru.
  348. Patched the close function for completeness (forgot again about the delayed
  349. expunge function, sigh.). Updates the SHOWPATCH program. Added a SetMan port
  350. of completeness.
  351. _____________________________________________________________________________
  352.  
  353. New in 2.06:
  354.  
  355. Added a new GURU and fixed a bug of the Expunge replacement. Thanks to
  356. Magnus for reporting!
  357. _____________________________________________________________________________
  358.  
  359. Thomas,
  360.     May 1998
  361.  
  362.  
  363. ============================= Archive contents =============================
  364.  
  365. Original  Packed Ratio    Date     Time    Name
  366. -------- ------- ----- --------- --------  -------------
  367.     3496    2294 34.3% 30-May-99 00:37:58 +SaferPatches
  368.    13021    4860 62.6% 30-May-99 00:39:12 +SaferPatches.readme
  369.     5004    3347 33.1% 09-Nov-97 23:44:56 +ShowPatch
  370. -------- ------- ----- --------- --------
  371.    21521   10501 51.2% 31-May-99 22:09:08   3 files
  372.